{ \bf Revision History}
-% Please do not use minipages in a tabular environment; this results
-% in bad vertical alignment.
-
-\begin{flushleft}
\begin{center}
- \begin{tabular}{|l|l|l|>{\raggedright}p{7cm}|}
+ \begin{tabular}{|l|l|l|l|}
\hline
1.0.0 & 27th April 07 & Xensource et al. &
- Initial Revision\tabularnewline
+ \begin{minipage}[t][.7cm]{7cm}
+ Initial Revision
+ \end{minipage}\\
\hline
1.0.1 & 10th Dec. 07 & S. Berger &
+ \begin{minipage}[t]{7cm}
+ \begin{flushleft}
Added XSPolicy.reset\_xspolicy, VTPM.get\_other\_config,
- VTPM.set\_otherconfig. ACMPolicy.get\_enforced\_binary methods.\tabularnewline
+ VTPM.set\_otherconfig. ACMPolicy.get\_enforced\_binary methods.
+ \end{flushleft}
+ \end{minipage}\\
\hline
1.0.2 & 25th Jan. 08 & J. Fehlig &
- Added Crashed VM power state.\tabularnewline
+ \begin{minipage}[t]{7cm}
+ \begin{flushleft}
+ Added Crashed VM power state.
+ \end{flushleft}
+ \end{minipage}\\
\hline
1.0.3 & 11th Feb. 08 & S. Berger &
- Added table of contents and hyperlink cross reference.\tabularnewline
+ \begin{minipage}[t]{7cm}
+ \begin{flushleft}
+ Added table of contents and hyperlink cross reference.
+ \end{flushleft}
+ \end{minipage}\\
\hline
1.0.4 & 23rd March 08 & S. Berger &
- Added XSPolicy.can\_run\tabularnewline
+ \begin{minipage}[t]{7cm}
+ \begin{flushleft}
+ Added XSPolicy.can\_run
+ \end{flushleft}
+ \end{minipage}\\
\hline
1.0.5 & 17th Apr. 08 & S. Berger &
+ \begin{minipage}[t]{7cm}
+ \begin{flushleft}
Added undocumented fields and methods for default\_netmask and
default\_gateway to the Network class. Removed an unimplemented
method from the XSPolicy class and removed the 'optional' from
- 'oldlabel' parameters.\tabularnewline
+ 'oldlabel' parameters.
+ \end{flushleft}
+ \end{minipage}\\
\hline
1.0.6 & 24th Jul. 08 & Y. Iwamatsu &
+ \begin{minipage}[t]{7cm}
+ \begin{flushleft}
Added definitions of new classes DPCI and PPCI. Updated the table
and the diagram representing relationships between classes.
- Added host.PPCIs and VM.DPCIs fields.\tabularnewline
+ Added host.PPCIs and VM.DPCIs fields.
+ \end{flushleft}
+ \end{minipage}\\
\hline
1.0.7 & 20th Oct. 08 & M. Kanno &
+ \begin{minipage}[t]{7cm}
+ \begin{flushleft}
Added definitions of new classes DSCSI and PSCSI. Updated the table
and the diagram representing relationships between classes.
- Added host.PSCSIs and VM.DSCSIs fields.\tabularnewline
- \hline
- 1.0.8 & 17th Jun. 09 & A. Florath &
- Updated interactive session example.
- Added description for \texttt{PV/kernel} and \texttt{PV/ramdisk}
- parameters using URIs.\tabularnewline
+ Added host.PSCSIs and VM.DSCSIs fields.
+ \end{flushleft}
+ \end{minipage}\\
\hline
\end{tabular}
\end{center}
-\end{flushleft}
%
% Copyright (c) 2006-2007 XenSource, Inc.
-% Copyright (c) 2009 flonatel GmbH & Co. KG
%
% Permission is granted to copy, distribute and/or modify this document under
% the terms of the GNU Free Documentation License, Version 1.2 or any later
% "GNU Free Documentation License" or the file fdl.tex.
%
% Authors: Ewan Mellor, Richard Sharp, Dave Scott, Jon Harrop.
-% Contributor: Andreas Florath
%
\chapter{API Reference}
\newpage
\section{Class: VM}
\subsection{Fields for class: VM}
-\begin{longtable}{|llp{0.21\textwidth}p{0.33\textwidth}|}
+\begin{longtable}{|lllp{0.38\textwidth}|}
\hline
\multicolumn{1}{|l}{Name} & \multicolumn{3}{l|}{\bf VM} \\
-\multicolumn{4}{|l|}{\parbox{11cm}{\em Description: A
+\multicolumn{1}{|l}{Description} & \multicolumn{3}{l|}{\parbox{11cm}{\em A
virtual machine (or 'guest').}} \\
\hline
Quals & Field & Type & Description \\
$\mathit{RO}_\mathit{run}$ & {\tt DPCIs} & (DPCI ref) Set & pass-through PCI devices \\
$\mathit{RO}_\mathit{run}$ & {\tt DSCSIs} & (DSCSI ref) Set & half-virtualized SCSI devices \\
$\mathit{RW}$ & {\tt PV/bootloader} & string & name of or path to bootloader \\
-$\mathit{RW}$ & {\tt PV/kernel} & string & URI of kernel \\
-$\mathit{RW}$ & {\tt PV/ramdisk} & string & URI of initrd \\
+$\mathit{RW}$ & {\tt PV/kernel} & string & path to the kernel \\
+$\mathit{RW}$ & {\tt PV/ramdisk} & string & path to the initrd \\
$\mathit{RW}$ & {\tt PV/args} & string & kernel command-line arguments \\
$\mathit{RW}$ & {\tt PV/bootloader\_args} & string & miscellaneous arguments for the bootloader \\
$\mathit{RW}$ & {\tt HVM/boot\_policy} & string & HVM boot policy \\
$\mathit{RO}_\mathit{run}$ & {\tt security/label} & string & the VM's security label \\
\hline
\end{longtable}
-\subsection{Parameter Details}
-\subsubsection{PV/kernel and PV/ramdisk}
-The \texttt{PV/kernel} and \texttt{PV/ramdisk} parameters should be
-specified as URIs with either a \texttt{file} or \texttt{data} scheme.
-
-The \texttt{file} scheme must be used when a file on the remote dom0
-should be used. The remote dom0 is the one where the guest system
-should be started on. Only absolute filenames are supported, i.e. the
-string must start with \texttt{file://} appended with the absolute
-path. This is typically used when the guest system use the same
-operating systems as the dom0 or there is some kind of shared storage
-for the images inside the dom0s.
-
-Note that for compatibility reasons it is possible --- but not
-recommended --- to leave out the scheme specification for
-\texttt{file}, i.e. \texttt{file:///some/path} and \texttt{/some/path}
-is equivalent.
-
-Examples (in python):
-
-Use kernel image which resides in the \texttt{/boot} directory:
-\begin{verbatim}
-xenapi.VM.create({ ...
- 'PV_kernel': 'file:///boot/vmlinuz-2.6.26-2-xen-686',
- ... })
-\end{verbatim}
-
-Use ramdisk image which resides on a (shared) nfs directory:
-\begin{verbatim}
-xenapi.VM.create({ ...
- 'PV_ramdisk': 'file:///nfs/xen/debian/5.0.1/initrd.img-2.6.26-2-xen-686'
- ... })
-\end{verbatim}
-
-When an image should be used which resides on the local system,
-i.e. the system where the XenAPI call is send from, it is possible to
-use the \texttt{data} URI scheme as described in \cite{RFC2397}. The
-media-type must be set to \texttt{application/octet-stream}.
-Currently only base64 encoding is supported. The URI must therefore
-start with \texttt{data:application/octet-stream;base64,} followed by
-the base64 encoded image.
-
-The \texttt{xen/util/fileuri.py} provides a helper function which
-takes a local filename as parameter and build up the correct URI from
-this.
-
-Examples (in python):
-
-Use kernel image specified inline:
-\begin{verbatim}
-xenapi.VM.create({ ...
- 'PV_kernel': 'data:application/octet-stream;base64,H4Zu....'
- # most of base64 encoded data is omitted
- ... })
-\end{verbatim}
-
-Using the utility function:
-\begin{verbatim}
-from xen.util.fileuri import scheme_data
-xenapi.VM.create({ ...
- 'PV_kernel': scheme_data.create_from_file(
- "/xen/guests/images/debian/5.0.1/vmlinuz-2.6.26-2-xen-686"),
- ... })
-\end{verbatim}
-
-Currently when using the \texttt{data} URI scheme, a temporary file is
-created on the remote dom0 in the directory
-\texttt{/var/run/xend/boot} which is then used for booting. When not
-used any longer the file is deleted. (Therefore reading of the
-\texttt{PV/kernel} or \texttt{PV/ramdisk} parameters when created with
-a \texttt{data} URI scheme returns a filename to a temporary file ---
-which might even not exists when querying.) This implementation might
-change in the way that the data is directly used --- without the
-indirection using a file. Therefore do not rely on the data resulting
-from a read of a variables which was set using the \texttt{data}
-scheme.
-
-Note: a mix of different schemes for the parameters is possible; e.g.
-the kernel can be specified with a \texttt{file} and the ramdisk with
-the \texttt{data} URI scheme.
-
\subsection{RPCs associated with class: VM}
\subsubsection{RPC name:~clone}
+++ /dev/null
-#============================================================================
-# This library is free software; you can redistribute it and/or
-# modify it under the terms of version 2.1 of the GNU Lesser General Public
-# License as published by the Free Software Foundation.
-#
-# This library is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
-# Lesser General Public License for more details.
-#
-# You should have received a copy of the GNU Lesser General Public
-# License along with this library; if not, write to the Free Software
-# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
-#============================================================================
-# Copyright (C) 2009 flonatel GmbH & Co. KG
-#============================================================================
-
-import logging
-import os
-import base64
-import tempfile
-import stat
-from xen.xend.XendLogging import log
-from xen.util import mkdir
-# The following are needed for unit-testing only
-import unittest
-
-#
-# This functions and classes can be used where a filename is expected -
-# especially in the xenapi.VM.create() for PV_kernel and PV_ramdisk.
-#
-# The functions have a backward compatibility mode, i.e. when there is
-# no appropriate scheme detected, the data is seens as a path to a
-# (local) file.
-#
-
-class scheme_error(Exception):
- def __init__(self, value):
- self.value = value
- def __str__(self):
- return repr(self.value)
-
-# Data scheme (as defined in RFC 2397):
-# data:application/octet-stream;base64,<base64 encoded data>
-# It looks that there is currently no general purpose implementation
-# available (in python) for this URL scheme - so the very basic is
-# done here.
-#
-# Limitations
-# o Only base64 is currently supported
-class scheme_data:
-
- def encode(data, mediatype = 'application/octet-stream',
- encoding = 'base64'):
- # XXX Limit this to base64 for current implementation
- if encoding!='base64':
- raise scheme_error("invalid encoding")
- return 'data:' + mediatype + ";" + encoding \
- + "," + base64.b64encode(data)
- encode = staticmethod(encode)
-
- # Private method: parse encoded data
- def parse(encoded_data):
- if not isinstance(encoded_data, str):
- raise scheme_error("encoded data has wrong type")
- if not encoded_data.startswith('data:'):
- raise scheme_error("'data:' scheme declaration missing")
- comma = encoded_data.find(',', 5)
- if comma == -1:
- raise scheme_error("data separator (comma) is missing")
- # Cut off the media type and encoding
- mtenc = encoded_data[5:comma]
- if len(mtenc)==0:
- raise scheme_error("encoding is empty")
- # XXX Limit to base64 encoding
- if not mtenc.endswith(';base64'):
- raise scheme_error("encoding is not base64")
- mediatype = mtenc[:-7]
- return (mediatype, 'base64', comma+1)
- parse = staticmethod(parse)
-
- # Stores the data in a local file and returns the filename
- # and a flag if this file in temporary only and must be deleted
- # after starting the VM.
- def decode(encoded_data):
- mkdir.parents("/var/run/xend/boot/", stat.S_IRWXU)
- mediatype, encoding, data_start = scheme_data.parse(encoded_data)
- fd, filename = tempfile.mkstemp(
- prefix="data_uri_file.", dir="/var/run/xend/boot")
- os.write(fd, base64.b64decode(encoded_data[data_start:]))
- os.close(fd)
- return filename, True
- decode = staticmethod(decode)
-
- # Utility function which reads in the given (local) file and
- # creates a data scheme from this.
- def create_from_file(filename):
- try:
- f = open(filename, "r")
- d = f.read()
- f.close()
- return scheme_data.encode(d)
- except IOError:
- raise scheme_error("file does not exists")
- create_from_file = staticmethod(create_from_file)
-
-class scheme_data_unit_tests(unittest.TestCase):
-
- def check_basic_encoding(self):
- "scheme_data - basic encoding"
- sd = scheme_data.encode('Hello!')
- self.assertEqual(sd, 'data:application/octet-stream;base64,SGVsbG8h')
-
- def check_encoding_with_given_mediatype(self):
- "scheme_data - encoding with given media name"
- sd = scheme_data.encode('Hello!', 'application/x-my-linux-kernel')
- self.assertEqual(sd,
- 'data:application/x-my-linux-kernel;base64,SGVsbG8h')
-
- def check_parse_01(self):
- "scheme_data - parsing of None"
- self.assertRaises(scheme_error, scheme_data.parse, None)
-
- def check_parse_02(self):
- "scheme_data - parsing of empty string"
- self.assertRaises(scheme_error, scheme_data.parse, "")
-
- def check_parse_03(self):
- "scheme_data - parsing of unstructured data"
- self.assertRaises(scheme_error, scheme_data.parse, "akskdjdfhezezu")
-
- def check_parse_04(self):
- "scheme_data - data: is not at the first place"
- self.assertRaises(scheme_error, scheme_data.parse, 'ggdata:sossm')
-
- def check_parse_05(self):
- "scheme_data - no comma in data"
- self.assertRaises(scheme_error, scheme_data.parse, 'data:sossm')
-
- def check_parse_06(self):
- "scheme_data - encoding is empty"
- self.assertRaises(scheme_error, scheme_data.parse, 'data:,')
-
- def check_parse_07(self):
- "scheme_data - unknown encoding"
- self.assertRaises(scheme_error, scheme_data.parse,
- 'data:somemediatype;unknown,')
-
- def check_parse_08(self):
- "scheme_data - parse ok - empty data"
- mediatype, encoding, data_start = scheme_data.parse(
- 'data:somemedia;base64,')
- self.assertEqual(mediatype, 'somemedia')
- self.assertEqual(encoding, 'base64')
- self.assertEqual(data_start, 22)
-
- def check_parse_09(self):
- "scheme_data - parse ok - some data"
- mediatype, encoding, data_start = scheme_data.parse(
- 'data:somemedia;base64,HereComesTheSun')
- self.assertEqual(mediatype, 'somemedia')
- self.assertEqual(encoding, 'base64')
- self.assertEqual(data_start, 22)
-
- def check_cff_file_does_not_exist(self):
- "scheme_data - create from file - non existent file"
- self.assertRaises(scheme_error, scheme_data.create_from_file,
- "/there/is/hopefully/no/file/like/this")
-
- def check_cff_ok(self):
- "scheme_data - create from file - ok"
- tmppath = "/tmp/scheme_data_check_cff_ok"
- f = open(tmppath, "w")
- f.write("huhuhu")
- f.close()
- d = scheme_data.create_from_file(tmppath)
- os.unlink(tmppath)
- self.assertEqual(d, "data:application/octet-stream;base64,aHVodWh1")
-
-# File Scheme
-# This class supports absolut paths only.
-class scheme_file:
-
- def encode(filename):
- if len(filename) == 0:
- raise scheme_error("filename is empty")
- if filename[0] != '/':
- raise scheme_error("filename is not absolut")
- return 'file://' + filename
- encode = staticmethod(encode)
-
- def decode(encoded_data):
- if not encoded_data.startswith("file://"):
- raise scheme_error("no file:// scheme found")
- path = encoded_data[7:]
- if len(path)==0:
- raise scheme_error("path is empty")
- if path[0]!='/':
- raise scheme_error("path is not absolute")
- return path, False
- decode = staticmethod(decode)
-
-class scheme_file_unit_tests(unittest.TestCase):
-
- def check_encode_empty_filename(self):
- "scheme_file - encode empty filename"
- self.assertRaises(scheme_error, scheme_file.encode, "")
-
- def check_encode_relative_filename(self):
- "scheme_file - encode relative filename"
- self.assertRaises(scheme_error, scheme_file.encode, "../there")
-
- def check_encode_absolut_filename(self):
- "scheme_file - encode absolut filename"
- self.assertEqual(
- scheme_file.encode("/here/and/there/again"),
- 'file:///here/and/there/again')
-
- def check_decode_01(self):
- "scheme_file - decode empty data"
- self.assertRaises(scheme_error, scheme_file.decode, "")
-
- def check_decode_02(self):
- "scheme_file - decode data with no file:// at the beginning (1)"
- self.assertRaises(scheme_error, scheme_file.decode,
- "phonehome://bbbb")
-
- def check_decode_03(self):
- "scheme_file - decode data with no file:// at the beginning (2)"
- self.assertRaises(scheme_error, scheme_file.decode,
- "file:/bbbb")
-
- def check_decode_04(self):
- "scheme_file - decode empty path"
- self.assertRaises(scheme_error, scheme_file.decode,
- "file://")
-
- def check_decode_05(self):
- "scheme_file - decode empty relative path"
- self.assertRaises(scheme_error, scheme_file.decode,
- "file://somewhere")
-
- def check_decode_06(self):
- "scheme_file - decode ok"
- path, tmp_file = scheme_file.decode("file:///boot/vmlinuz")
- self.assertEqual(path, "/boot/vmlinuz")
- self.assertEqual(tmp_file, False)
-
-class scheme_set:
-
- def __init__(self):
- self.schemes = [scheme_data, scheme_file]
-
- def decode(self, uri):
- for scheme in self.schemes:
- try:
- # If this passes, it is the correct scheme
- return scheme.decode(uri)
- except scheme_error, se:
- log.debug("Decode throws an error: '%s'" % se)
- return uri, False
-
-schemes = scheme_set()
-
-
-def suite():
- return unittest.TestSuite(
- [unittest.makeSuite(scheme_data_unit_tests, 'check_'),
- unittest.makeSuite(scheme_file_unit_tests, 'check_'),])
-
-if __name__ == "__main__":
- testresult = unittest.TextTestRunner(verbosity=3).run(suite())
-
projects / xen.git / commitdiff